home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kaccel.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  13.1 KB  |  391 lines
  1. /* This file is part of the KDE libraries
  2.     Copyright (C) 2001,2002 Ellis Whitehead <ellis@kde.org>
  3.  
  4.     This library is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU Library General Public
  6.     License as published by the Free Software Foundation; either
  7.     version 2 of the License, or (at your option) any later version.
  8.  
  9.     This library is distributed in the hope that it will be useful,
  10.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.     Library General Public License for more details.
  13.  
  14.     You should have received a copy of the GNU Library General Public License
  15.     along with this library; see the file COPYING.LIB.  If not, write to
  16.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.     Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef _KACCEL_H
  21. #define _KACCEL_H
  22.  
  23. #include <qaccel.h>
  24. #include <kshortcut.h>
  25. #include <kstdaccel.h>
  26. #include "kdelibs_export.h"
  27.  
  28. class QPopupMenu; // for obsolete insertItem() methods below
  29. class QWidget;
  30. class KAccelAction;
  31. class KAccelActions;
  32. class KConfigBase;
  33.  
  34. class KAccelPrivate;
  35. /**
  36.  * Handle shortcuts.
  37.  *
  38.  * Allow a user to configure shortcuts
  39.  * through application configuration files or through the
  40.  * KKeyChooser GUI.
  41.  *
  42.  * A KAccel contains a list of accelerator actions.
  43.  *
  44.  * For example, CTRL+Key_P could be a shortcut for printing a document. The key
  45.  * codes are listed in qnamespace.h. "Print" could be the action name for printing.
  46.  * The action name identifies the shortcut in configuration files and the
  47.  * KKeyChooser GUI.
  48.  *
  49.  * A KAccel object handles key events sent to its parent widget and to all
  50.  * children of this parent widget.  The most recently created KAccel object
  51.  * has precedence over any KAccel objects created before it.
  52.  * When a shortcut pressed, KAccel calls the slot to which it has been
  53.  * connected. If you want to set global accelerators, independent of the window
  54.  * which has the focus, use KGlobalAccel.
  55.  *
  56.  * Reconfiguration of a given shortcut can be prevented by specifying
  57.  * that an accelerator item is not configurable when it is inserted. A special
  58.  * group of non-configurable key bindings are known as the
  59.  * standard accelerators.
  60.  *
  61.  * The standard accelerators appear repeatedly in applications for
  62.  * standard document actions such as printing and saving. A convenience method is
  63.  * available to insert and connect these accelerators which are configurable on
  64.  * a desktop-wide basis.
  65.  *
  66.  * It is possible for a user to choose to have no key associated with
  67.  * an action.
  68.  *
  69.  * The translated first argument for insertItem() is used only
  70.  * in the configuration dialog.
  71.  *\code
  72.  * KAccel* pAccel = new KAccel( this );
  73.  *
  74.  * // Insert an action "Scroll Up" which is associated with the "Up" key:
  75.  * pAccel->insert( "Scroll Up", i18n("Scroll up"),
  76.  *                       i18n("Scroll up the current document by one line."),
  77.  *                       Qt::Key_Up, this, SLOT(slotScrollUp()) );
  78.  * // Insert an standard acclerator action.
  79.  * pAccel->insert( KStdAccel::Print, this, SLOT(slotPrint()) );
  80.  *
  81.  * // Update the shortcuts by read any user-defined settings from the
  82.  * // application's config file.
  83.  * pAccel->readSettings();
  84.  * \endcode
  85.  *
  86.  * @short Configurable shortcut support for widgets.
  87.  * @see KGlobalAccel
  88.  * @see KAccelShortcutList
  89.  * @see KKeyChooser
  90.  * @see KKeyDialog
  91.  */
  92.  
  93. class KDECORE_EXPORT KAccel : public QAccel
  94. {
  95.     Q_OBJECT
  96.  public:
  97.     /**
  98.      * Creates a new KAccel that watches @p pParent, which is also
  99.      * the QObject's parent.
  100.      *
  101.      * @param pParent the parent and widget to watch for key strokes
  102.      * @param psName the name of the QObject
  103.      */
  104.     KAccel( QWidget* pParent, const char* psName = 0 );
  105.  
  106.     /**
  107.      * Creates a new KAccel that watches @p watch.
  108.      *
  109.      * @param watch the widget to watch for key strokes
  110.      * @param parent the parent of the QObject
  111.      * @param psName the name of the QObject
  112.      */
  113.     KAccel( QWidget* watch, QObject* parent, const char* psName = 0 );
  114.     virtual ~KAccel();
  115.  
  116.     /**
  117.      * @internal
  118.      * Returns the KAccel's @p KAccelActions, a list of @p KAccelAction.
  119.      * @return the KAccelActions of the KAccel
  120.      */
  121.     KAccelActions& actions();
  122.  
  123.     /**
  124.      * @internal
  125.      * Returns the KAccel's @p KAccelActions, a list of @p KAccelAction.
  126.      * @return the KAccelActions of the KAccel
  127.      */
  128.     const KAccelActions& actions() const;
  129.  
  130.     /**
  131.      * Checks whether the KAccel is active.
  132.      * @return true if the QAccel is enabled
  133.      */
  134.     bool isEnabled();
  135.  
  136.     /**
  137.      * Enables or disables the KAccel.
  138.      * @param bEnabled true to enable, false to disable
  139.      */
  140.     void setEnabled( bool bEnabled );
  141.  
  142.     /**
  143.      * Enable auto-update of connections. This means that the signals
  144.      * are automatically disconnected when you disable an action, and
  145.      * re-enabled when you enable it. By default auto update is turned
  146.      * on. If you disable auto-update, you need to call
  147.      * updateConnections() after changing actions.
  148.      *
  149.      * @param bAuto true to enable, false to disable
  150.      * @return the value of the flag before this call
  151.      */
  152.     bool setAutoUpdate( bool bAuto );
  153.  
  154.     /**
  155.      * Create an accelerator action.
  156.      *
  157.      * Usage:
  158.      *\code
  159.      * insert( "Do Something", i18n("Do Something"),
  160.      *   i18n("This action allows you to do something really great with this program to "
  161.      *        "the currently open document."),
  162.      *   ALT+Key_D, this, SLOT(slotDoSomething()) );
  163.      *\endcode
  164.      *
  165.      * @param sAction The internal name of the action.
  166.      * @param sLabel An i18n'ized short description of the action displayed when
  167.      *  using KKeyChooser to reconfigure the shortcuts.
  168.      * @param sWhatsThis An extended description of the action.
  169.      * @param cutDef The default shortcut.
  170.      * @param pObjSlot Pointer to the slot object.
  171.      * @param psMethodSlot Pointer to the slot method.
  172.      * @param bConfigurable Allow the user to change this shortcut if set to 'true'.
  173.      * @param bEnabled The action will be activated by the shortcut if set to 'true'.
  174.      */
  175.     KAccelAction* insert( const QString& sAction, const QString& sLabel, const QString& sWhatsThis,
  176.                      const KShortcut& cutDef,
  177.                      const QObject* pObjSlot, const char* psMethodSlot,
  178.                      bool bConfigurable = true, bool bEnabled = true );
  179.     /**
  180.      * Same as first insert(), but with separate shortcuts defined for
  181.      * 3- and 4- modifier defaults.
  182.      */
  183.     KAccelAction* insert( const QString& sAction, const QString& sLabel, const QString& sWhatsThis,
  184.                      const KShortcut& cutDef3, const KShortcut& cutDef4,
  185.                      const QObject* pObjSlot, const char* psMethodSlot,
  186.                      bool bConfigurable = true, bool bEnabled = true );
  187.     /**
  188.      * This is an overloaded function provided for convenience.
  189.      * The advantage of this is when you want to use the same text for the name
  190.      * of the action as for the user-visible label.
  191.      *
  192.      * Usage:
  193.      * \code
  194.      * insert( i18n("Do Something"), ALT+Key_D, this, SLOT(slotDoSomething()) );
  195.      * \endcode
  196.      *
  197.      * @param psAction The name AND label of the action.
  198.      * @param cutDef The default shortcut for this action.
  199.      * @param pObjSlot Pointer to the slot object.
  200.      * @param psMethodSlot Pointer to the slot method.
  201.      * @param bConfigurable Allow the user to change this shortcut if set to 'true'.
  202.      * @param bEnabled The action will be activated by the shortcut if set to 'true'.
  203.      */
  204.     KAccelAction* insert( const char* psAction, const KShortcut& cutDef,
  205.                      const QObject* pObjSlot, const char* psMethodSlot,
  206.                      bool bConfigurable = true, bool bEnabled = true );
  207.     /**
  208.      * Similar to the first insert() method, but with the action
  209.      * name, short description, help text, and default shortcuts all
  210.      * set according to one of the standard accelerators.
  211.      * @see KStdAccel.
  212.      */
  213.     KAccelAction* insert( KStdAccel::StdAccel id,
  214.                      const QObject* pObjSlot, const char* psMethodSlot,
  215.                      bool bConfigurable = true, bool bEnabled = true );
  216.  
  217.         /**
  218.          * Removes the accelerator action identified by the name.
  219.          * Remember to also call updateConnections().
  220.      * @param sAction the name of the action to remove
  221.      * @return true if successful, false otherwise
  222.          */
  223.     bool remove( const QString& sAction );
  224.  
  225.     /**
  226.      * Updates the connections of the accelerations after changing them.
  227.      * This is only necessary if you have disabled auto updates which are
  228.      * on by default.
  229.      * @return true if successful, false otherwise
  230.      * @see setAutoUpdate()
  231.      * @see getAutoUpdate()
  232.      */
  233.     bool updateConnections();
  234.  
  235.     /**
  236.      * Return the shortcut associated with the action named by @p sAction.
  237.      * @param sAction the name of the action
  238.      * @return the action's shortcut, or a null shortcut if not found
  239.      */
  240.     const KShortcut& shortcut( const QString& sAction ) const;
  241.  
  242.     /**
  243.      * Set the shortcut to be associated with the action named by @p sAction.
  244.      * @param sAction the name of the action
  245.      * @param shortcut the shortcut to set
  246.      * @return true if successful, false otherwise
  247.      */
  248.     bool setShortcut( const QString& sAction, const KShortcut &shortcut );
  249.  
  250.     /**
  251.      * Set the slot to be called when the shortcut of the action named
  252.      * by @p sAction is pressed.
  253.      * @param sAction the name of the action
  254.      * @param pObjSlot the owner of the slot
  255.      * @param psMethodSlot the name of the slot
  256.      * @return true if successful, false otherwise
  257.      */
  258.     bool setSlot( const QString& sAction, const QObject* pObjSlot, const char* psMethodSlot );
  259.     /**
  260.      * Enable or disable the action named by @p sAction.
  261.      * @param sAction the action to en-/disable
  262.      * @param bEnabled true to enable, false to disable
  263.      * @return true if successful, false otherwise
  264.      */
  265.     bool setEnabled( const QString& sAction, bool bEnabled );
  266.  
  267.     /**
  268.      * Returns the configuration group of the settings.
  269.      * @return the configuration group
  270.      * @see KConfig
  271.      */
  272.     const QString& configGroup() const;
  273.  
  274.     /**
  275.      * Returns the configuration group of the settings.
  276.      * @param name the new configuration group
  277.      * @see KConfig
  278.      */
  279.     void setConfigGroup( const QString &name );
  280.  
  281.     /**
  282.      * Read all shortcuts from @p pConfig, or (if @p pConfig
  283.      * is zero) from the application's configuration file
  284.      * KGlobal::config().
  285.      *
  286.      * The group in which the configuration is stored can be
  287.      * set with setConfigGroup().
  288.      * @param pConfig the configuration file, or 0 for the application
  289.      *         configuration file
  290.      * @return true if successful, false otherwise
  291.      */
  292.     bool readSettings( KConfigBase* pConfig = 0 );
  293.     /**
  294.      * Write the current shortcuts to @p pConfig,
  295.      * or (if @p pConfig is zero) to the application's
  296.      * configuration file.
  297.      * @param pConfig the configuration file, or 0 for the application
  298.      *         configuration file
  299.      * @return true if successful, false otherwise
  300.      */
  301.     bool writeSettings( KConfigBase* pConfig = 0 ) const;
  302.  
  303.     /**
  304.      * Emits the keycodeChanged() signal.
  305.      */
  306.     void emitKeycodeChanged();
  307.  
  308.  signals:
  309.     /**
  310.      * Emitted when one of the key codes has changed.
  311.      */
  312.     void keycodeChanged();
  313.  
  314. #ifndef KDE_NO_COMPAT
  315.  public:
  316.     // Source compatibility to KDE 2.x
  317.     /**
  318.      * @deprecated use insert
  319.      */
  320.     bool insertItem( const QString& sLabel, const QString& sAction,
  321.                      const char* psKey,
  322.                      int nIDMenu = 0, QPopupMenu* pMenu = 0, bool bConfigurable = true ) KDE_DEPRECATED;
  323.     /**
  324.      * @deprecated use insert
  325.      */
  326.     bool insertItem( const QString& sLabel, const QString& sAction,
  327.                      int key,
  328.                      int nIDMenu = 0, QPopupMenu* pMenu = 0, bool bConfigurable = true ) KDE_DEPRECATED;
  329.     /**
  330.      * @deprecated use insert
  331.      */
  332.     bool insertStdItem( KStdAccel::StdAccel id, const QString& descr = QString::null ) KDE_DEPRECATED;
  333.     /**
  334.      * @deprecated use insert
  335.      */
  336.     bool connectItem( const QString& sAction, const QObject* pObjSlot, const char* psMethodSlot, bool bActivate = true ) KDE_DEPRECATED;
  337.     /**
  338.      * @deprecated use insert( accel, pObjSlot, psMethodSlot );
  339.      *
  340.      */
  341.     KDE_DEPRECATED bool connectItem( KStdAccel::StdAccel accel, const QObject* pObjSlot, const char* psMethodSlot )
  342.         { return insert( accel, pObjSlot, psMethodSlot ); }
  343.     /**
  344.      * @deprecated use remove
  345.      */
  346.     bool removeItem( const QString& sAction ) KDE_DEPRECATED;
  347.     /**
  348.      * @deprecated
  349.      */
  350.     bool setItemEnabled( const QString& sAction, bool bEnable ) KDE_DEPRECATED;
  351.     /**
  352.      * @deprecated see KDE3PORTING.html
  353.      */
  354.     void changeMenuAccel( QPopupMenu *menu, int id, const QString& action ) KDE_DEPRECATED;
  355.     /**
  356.      * @deprecated see KDE3PORTING.html
  357.      */
  358.     void changeMenuAccel( QPopupMenu *menu, int id, KStdAccel::StdAccel accel ) KDE_DEPRECATED;
  359.     /**
  360.      * @deprecated
  361.      */
  362.     static int stringToKey( const QString& ) KDE_DEPRECATED;
  363.  
  364.     /**
  365.      * @deprecated  Use shortcut().
  366.      *
  367.      * Retrieve the key code of the accelerator item with the action name
  368.      * @p action, or zero if either the action name cannot be
  369.      * found or the current key is set to no key.
  370.      */
  371.     int currentKey( const QString& action ) const KDE_DEPRECATED;
  372.  
  373.     /**
  374.      * @deprecated  Use actions().actionPtr().
  375.      *
  376.      * Return the name of the accelerator item with the keycode @p key,
  377.      * or QString::null if the item cannot be found.
  378.      */
  379.     QString findKey( int key ) const KDE_DEPRECATED;
  380. #endif // !KDE_NO_COMPAT
  381.  
  382.  protected:
  383.         /** \internal */
  384.     virtual void virtual_hook( int id, void* data );
  385.  private:
  386.     class KAccelPrivate* d;
  387.     friend class KAccelPrivate;
  388. };
  389.  
  390. #endif // _KACCEL_H
  391.